package org.vaadin.nf4v.core.navigation;

import com.vaadin.ui.Component;
import org.vaadin.nf4v.core.navigation.event.NavigationState;
import org.vaadin.nf4v.core.navigation.target.NavigationTarget;
import org.vaadin.nf4v.core.util.Params;

import java.io.Serializable;

/**
 * Request object represent navigation lifecycle.
 * It is created around navigation target.
 * It holds all known information about current navigation process (target, page instance, parsed parameters etc.).
 * It is possible to cancel current navigation in NavigationListener using cancel() method of request.
 */
public interface NavigationRequest extends Serializable {

    /**
     * Request state represents navigation phase. On each phase all listeners are notified with request instance.
     *
     * @return request state
     */
    NavigationState getState();

    /**
     * @return request initiator (URI or API)
     */
    RequestInitiatorType getRequestInitiatorType();

    /**
     * @return target object
     */
    NavigationTarget getTarget();

    /**
     * Note: page instance is available only after PAGE_INSTANTIATED state
     *
     * @return page instance
     */
    Component getPageInstance();

    /**
     * Note: correct value will be set only after reaching PAGE_NAVIGATION or PAGE_PARAMETERS_CHANGE state
     *
     * @return true if request is parameters change request
     */
    boolean isParametersChangeRequest();

    /**
     * Cancels request.
     * Be careful, if initial home page request will be interrupted and no other request will be performed
     * in listener, no page will be shown!
     * <p/>
     * It in not possible to cancel request after BEFORE_NAVIGATION state
     */
    void cancel();

    /**
     * @return true if request is cancelled, false otherwise
     */
    boolean isCancelled();

    /**
     * @return params utility, which provides easy access to parsed parameters inside target object
     */
    Params params();
}
